home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / cairo / cairo.h < prev   
C/C++ Source or Header  |  2006-04-25  |  47KB  |  1,456 lines
  1. /* cairo - a vector graphics library with display and print output
  2.  *
  3.  * Copyright ┬⌐ 2002 University of Southern California
  4.  * Copyright ┬⌐ 2005 Red Hat, Inc.
  5.  *
  6.  * This library is free software; you can redistribute it and/or
  7.  * modify it either under the terms of the GNU Lesser General Public
  8.  * License version 2.1 as published by the Free Software Foundation
  9.  * (the "LGPL") or, at your option, under the terms of the Mozilla
  10.  * Public License Version 1.1 (the "MPL"). If you do not alter this
  11.  * notice, a recipient may use your version of this file under either
  12.  * the MPL or the LGPL.
  13.  *
  14.  * You should have received a copy of the LGPL along with this library
  15.  * in the file COPYING-LGPL-2.1; if not, write to the Free Software
  16.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  17.  * You should have received a copy of the MPL along with this library
  18.  * in the file COPYING-MPL-1.1
  19.  *
  20.  * The contents of this file are subject to the Mozilla Public License
  21.  * Version 1.1 (the "License"); you may not use this file except in
  22.  * compliance with the License. You may obtain a copy of the License at
  23.  * http://www.mozilla.org/MPL/
  24.  *
  25.  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
  26.  * OF ANY KIND, either express or implied. See the LGPL or the MPL for
  27.  * the specific language governing rights and limitations.
  28.  *
  29.  * The Original Code is the cairo graphics library.
  30.  *
  31.  * The Initial Developer of the Original Code is University of Southern
  32.  * California.
  33.  *
  34.  * Contributor(s):
  35.  *    Carl D. Worth <cworth@cworth.org>
  36.  */
  37.  
  38. #ifndef CAIRO_H
  39. #define CAIRO_H
  40.  
  41. #include <cairo-features.h>
  42.  
  43. CAIRO_BEGIN_DECLS
  44.  
  45. #define CAIRO_VERSION_ENCODE(major, minor, micro) (     \
  46.       ((major) * 10000)                             \
  47.     + ((minor) *   100)                             \
  48.     + ((micro) *     1))
  49.  
  50. #define CAIRO_VERSION CAIRO_VERSION_ENCODE(     \
  51.     CAIRO_VERSION_MAJOR,                    \
  52.     CAIRO_VERSION_MINOR,                    \
  53.     CAIRO_VERSION_MICRO)
  54.  
  55. int
  56. cairo_version (void);
  57.  
  58. const char*
  59. cairo_version_string (void);
  60.  
  61. /**
  62.  * cairo_bool_t:
  63.  *
  64.  * #cairo_bool_t is used for boolean values. Returns of type
  65.  * #cairo_bool_t will always be either 0 or 1, but testing against
  66.  * these values explicitly is not encouraged; just use the
  67.  * value as a boolean condition.
  68.  *
  69.  * <informalexample><programlisting>
  70.  *  if (cairo_in_stroke (cr, x, y)) {
  71.  *      /<!-- -->* do something *<!-- -->/
  72.  *  }
  73.  * </programlisting></informalexample>
  74.  */
  75. typedef int cairo_bool_t;
  76.  
  77. /**
  78.  * cairo_t:
  79.  *
  80.  * A #cairo_t contains the current state of the rendering device,
  81.  * including coordinates of yet to be drawn shapes.
  82.  **/
  83. typedef struct _cairo cairo_t;
  84.  
  85. /**
  86.  * cairo_surface_t:
  87.  *
  88.  * A #cairo_surface_t represents an image, either as the destination
  89.  * of a drawing operation or as source when drawing onto another
  90.  * surface. There are different subtypes of cairo_surface_t for
  91.  * different drawing backends; for example, cairo_image_surface_create()
  92.  * creates a bitmap image in memory.
  93.  *
  94.  * Memory management of #cairo_surface_t is done with
  95.  * cairo_surface_reference() and cairo_surface_destroy().
  96.  */
  97. typedef struct _cairo_surface cairo_surface_t;
  98.  
  99. /**
  100.  * cairo_matrix_t:
  101.  * @xx: xx component of the affine transformation
  102.  * @yx: yx component of the affine transformation
  103.  * @xy: xy component of the affine transformation
  104.  * @yy: yy component of the affine transformation
  105.  * @x0: X translation component of the affine transformation
  106.  * @y0: Y translation component of the affine transformation
  107.  *
  108.  * A #cairo_matrix_t holds an affine transformation, such as a scale,
  109.  * rotation, shear, or a combination of those. The transformation of
  110.  * a point (x, y) is given by:
  111.  * <programlisting>
  112.  *     x_new = xx * x + xy * y + x0;
  113.  *     y_new = yx * x + yy * y + y0;
  114.  * </programlisting>
  115.  **/
  116. typedef struct _cairo_matrix {
  117.     double xx; double yx;
  118.     double xy; double yy;
  119.     double x0; double y0;
  120. } cairo_matrix_t;
  121.  
  122. typedef struct _cairo_pattern cairo_pattern_t;
  123.  
  124. /**
  125.  * cairo_destroy_func_t:
  126.  * @data: The data element being destroyed.
  127.  *
  128.  * #cairo_destroy_func_t the type of function which is called when a
  129.  * data element is destroyed. It is passed the pointer to the data
  130.  * element and should free any memory and resources allocated for it.
  131.  */
  132. typedef void (*cairo_destroy_func_t) (void *data);
  133.  
  134. /**
  135.  * cairo_user_data_key_t:
  136.  * @unused: not used; ignore.
  137.  *
  138.  * #cairo_user_data_key_t is used for attaching user data to cairo
  139.  * data structures.  The actual contents of the struct is never used,
  140.  * and there is no need to initialize the object; only the unique
  141.  * address of a #cairo_data_key_t object is used.  Typically, you
  142.  * would just use the address of a static #cairo_data_key_t object.
  143.  */
  144. typedef struct _cairo_user_data_key {
  145.     int unused;
  146. } cairo_user_data_key_t;
  147.  
  148. /**
  149.  * cairo_status_t
  150.  * @CAIRO_STATUS_SUCCESS: no error has occurred
  151.  * @CAIRO_STATUS_NO_MEMORY: out of memory
  152.  * @CAIRO_STATUS_INVALID_RESTORE: cairo_restore without matching cairo_save
  153.  * @CAIRO_STATUS_INVALID_POP_GROUP: no saved group to pop
  154.  * @CAIRO_STATUS_NO_CURRENT_POINT: no current point defined
  155.  * @CAIRO_STATUS_INVALID_MATRIX: invalid matrix (not invertible)
  156.  * @CAIRO_STATUS_INVALID_STATUS: invalid value for an input cairo_status_t
  157.  * @CAIRO_STATUS_NULL_POINTER: NULL pointer
  158.  * @CAIRO_STATUS_INVALID_STRING: input string not valid UTF-8
  159.  * @CAIRO_STATUS_INVALID_PATH_DATA: input path data not valid
  160.  * @CAIRO_STATUS_READ_ERROR: error while reading from input stream
  161.  * @CAIRO_STATUS_WRITE_ERROR: error while writing to output stream
  162.  * @CAIRO_STATUS_SURFACE_FINISHED: target surface has been finished
  163.  * @CAIRO_STATUS_SURFACE_TYPE_MISMATCH: the surface type is not appropriate for the operation
  164.  * @CAIRO_STATUS_PATTERN_TYPE_MISMATCH: the pattern type is not appropriate for the operation
  165.  * @CAIRO_STATUS_INVALID_CONTENT: invalid value for an input cairo_content_t
  166.  * @CAIRO_STATUS_INVALID_FORMAT: invalid value for an input cairo_format_t
  167.  * @CAIRO_STATUS_INVALID_VISUAL: invalid value for an input Visual*
  168.  * @CAIRO_STATUS_FILE_NOT_FOUND: file not found
  169.  * @CAIRO_STATUS_INVALID_DASH: invalid value for a dash setting
  170.  *
  171.  * #cairo_status_t is used to indicate errors that can occur when
  172.  * using Cairo. In some cases it is returned directly by functions.
  173.  * but when using #cairo_t, the last error, if any, is stored in
  174.  * the context and can be retrieved with cairo_status().
  175.  **/
  176. typedef enum _cairo_status {
  177.     CAIRO_STATUS_SUCCESS = 0,
  178.     CAIRO_STATUS_NO_MEMORY,
  179.     CAIRO_STATUS_INVALID_RESTORE,
  180.     CAIRO_STATUS_INVALID_POP_GROUP,
  181.     CAIRO_STATUS_NO_CURRENT_POINT,
  182.     CAIRO_STATUS_INVALID_MATRIX,
  183.     CAIRO_STATUS_INVALID_STATUS,
  184.     CAIRO_STATUS_NULL_POINTER,
  185.     CAIRO_STATUS_INVALID_STRING,
  186.     CAIRO_STATUS_INVALID_PATH_DATA,
  187.     CAIRO_STATUS_READ_ERROR,
  188.     CAIRO_STATUS_WRITE_ERROR,
  189.     CAIRO_STATUS_SURFACE_FINISHED,
  190.     CAIRO_STATUS_SURFACE_TYPE_MISMATCH,
  191.     CAIRO_STATUS_PATTERN_TYPE_MISMATCH,
  192.     CAIRO_STATUS_INVALID_CONTENT,
  193.     CAIRO_STATUS_INVALID_FORMAT,
  194.     CAIRO_STATUS_INVALID_VISUAL,
  195.     CAIRO_STATUS_FILE_NOT_FOUND,
  196.     CAIRO_STATUS_INVALID_DASH
  197. } cairo_status_t;
  198.  
  199. /**
  200.  * cairo_write_func_t:
  201.  * @closure: the output closure
  202.  * @data: the buffer containing the data to write
  203.  * @length: the amount of data to write
  204.  *
  205.  * #cairo_write_func_t is the type of function which is called when a
  206.  * backend needs to write data to an output stream.  It is passed the
  207.  * closure which was specified by the user at the time the write
  208.  * function was registered, the data to write and the length of the
  209.  * data in bytes.  The write function should return
  210.  * CAIRO_STATUS_SUCCESS if all the data was successfully written,
  211.  * CAIRO_STATUS_WRITE_ERROR otherwise.
  212.  *
  213.  * Returns: the status code of the write operation
  214.  */
  215. typedef cairo_status_t (*cairo_write_func_t) (void          *closure,
  216.                           const unsigned char *data,
  217.                           unsigned int       length);
  218.  
  219. /**
  220.  * cairo_read_func_t:
  221.  * @closure: the input closure
  222.  * @data: the buffer into which to read the data
  223.  * @length: the amount of data to read
  224.  *
  225.  * #cairo_read_func_t is the type of function which is called when a
  226.  * backend needs to read data from an intput stream.  It is passed the
  227.  * closure which was specified by the user at the time the read
  228.  * function was registered, the buffer to read the data into and the
  229.  * length of the data in bytes.  The read function should return
  230.  * CAIRO_STATUS_SUCCESS if all the data was successfully read,
  231.  * CAIRO_STATUS_READ_ERROR otherwise.
  232.  *
  233.  * Returns: the status code of the read operation
  234.  */
  235. typedef cairo_status_t (*cairo_read_func_t) (void        *closure,
  236.                          unsigned char    *data,
  237.                          unsigned int    length);
  238.  
  239. /* Functions for manipulating state objects */
  240. cairo_t *
  241. cairo_create (cairo_surface_t *target);
  242.  
  243. cairo_t *
  244. cairo_reference (cairo_t *cr);
  245.  
  246. void
  247. cairo_destroy (cairo_t *cr);
  248.  
  249. void
  250. cairo_save (cairo_t *cr);
  251.  
  252. void
  253. cairo_restore (cairo_t *cr);
  254.  
  255. /* XXX: I want to rethink this API
  256. void
  257. cairo_push_group (cairo_t *cr);
  258.  
  259. void
  260. cairo_pop_group (cairo_t *cr);
  261. */
  262.  
  263. /* Modify state */
  264.  
  265. typedef enum _cairo_operator {
  266.     CAIRO_OPERATOR_CLEAR,
  267.  
  268.     CAIRO_OPERATOR_SOURCE,
  269.     CAIRO_OPERATOR_OVER,
  270.     CAIRO_OPERATOR_IN,
  271.     CAIRO_OPERATOR_OUT,
  272.     CAIRO_OPERATOR_ATOP,
  273.  
  274.     CAIRO_OPERATOR_DEST,
  275.     CAIRO_OPERATOR_DEST_OVER,
  276.     CAIRO_OPERATOR_DEST_IN,
  277.     CAIRO_OPERATOR_DEST_OUT,
  278.     CAIRO_OPERATOR_DEST_ATOP,
  279.  
  280.     CAIRO_OPERATOR_XOR,
  281.     CAIRO_OPERATOR_ADD,
  282.     CAIRO_OPERATOR_SATURATE
  283. } cairo_operator_t;
  284.  
  285. void
  286. cairo_set_operator (cairo_t *cr, cairo_operator_t op);
  287.  
  288. void
  289. cairo_set_source (cairo_t *cr, cairo_pattern_t *source);
  290.  
  291. void
  292. cairo_set_source_rgb (cairo_t *cr, double red, double green, double blue);
  293.  
  294. void
  295. cairo_set_source_rgba (cairo_t *cr,
  296.                double red, double green, double blue,
  297.                double alpha);
  298.  
  299. void
  300. cairo_set_source_surface (cairo_t      *cr,
  301.               cairo_surface_t *surface,
  302.               double       x,
  303.               double       y);
  304.  
  305. void
  306. cairo_set_tolerance (cairo_t *cr, double tolerance);
  307.  
  308. /**
  309.  * cairo_antialias_t:
  310.  * @CAIRO_ANTIALIAS_DEFAULT: Use the default antialiasing for
  311.  *   the subsystem and target device
  312.  * @CAIRO_ANTIALIAS_NONE: Use a bilevel alpha mask
  313.  * @CAIRO_ANTIALIAS_GRAY: Perform single-color antialiasing (using
  314.  *  shades of gray for black text on a white background, for example).
  315.  * @CAIRO_ANTIALIAS_SUBPIXEL: Perform antialiasing by taking
  316.  *  advantage of the order of subpixel elements on devices
  317.  *  such as LCD panels
  318.  * 
  319.  * Specifies the type of antialiasing to do when rendering text or shapes.
  320.  **/
  321. typedef enum _cairo_antialias {
  322.     CAIRO_ANTIALIAS_DEFAULT,
  323.     CAIRO_ANTIALIAS_NONE,
  324.     CAIRO_ANTIALIAS_GRAY,
  325.     CAIRO_ANTIALIAS_SUBPIXEL
  326. } cairo_antialias_t;
  327.  
  328. void
  329. cairo_set_antialias (cairo_t *cr, cairo_antialias_t antialias);
  330.  
  331. /**
  332.  * cairo_fill_rule_t
  333.  * @CAIRO_FILL_RULE_WINDING: If the path crosses the ray from
  334.  * left-to-right, counts +1. If the path crosses the ray
  335.  * from right to left, counts -1. (Left and right are determined
  336.  * from the perspective of looking along the ray from the starting
  337.  * point.) If the total count is non-zero, the point will be filled.
  338.  * @CAIRO_FILL_RULE_EVEN_ODD: Counts the total number of
  339.  * intersections, without regard to the orientation of the contour. If
  340.  * the total number of intersections is odd, the point will be
  341.  * filled.
  342.  *
  343.  * #cairo_fill_rule_t is used to select how paths are filled. For both
  344.  * fill rules, whether or not a point is included in the fill is
  345.  * determined by taking a ray from that point to infinity and looking
  346.  * at intersections with the path. The ray can be in any direction,
  347.  * as long as it doesn't pass through the end point of a segment
  348.  * or have a tricky intersection such as intersecting tangent to the path.
  349.  * (Note that filling is not actually implemented in this way. This
  350.  * is just a description of the rule that is applied.)
  351.  **/
  352. typedef enum _cairo_fill_rule {
  353.     CAIRO_FILL_RULE_WINDING,
  354.     CAIRO_FILL_RULE_EVEN_ODD
  355. } cairo_fill_rule_t;
  356.  
  357. void
  358. cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule);
  359.  
  360. void
  361. cairo_set_line_width (cairo_t *cr, double width);
  362.  
  363.  
  364. /**
  365.  * cairo_line_cap_t
  366.  * @CAIRO_LINE_CAP_BUTT: start(stop) the line exactly at the start(end) point
  367.  * @CAIRO_LINE_CAP_ROUND: use a round ending, the center of the circle is the end point
  368.  * @CAIRO_LINE_CAP_SQUARE: use squared ending, the center of the square is the end point
  369.  *
  370.  * enumeration for style of line-endings
  371.  **/
  372. typedef enum _cairo_line_cap {
  373.     CAIRO_LINE_CAP_BUTT,
  374.     CAIRO_LINE_CAP_ROUND,
  375.     CAIRO_LINE_CAP_SQUARE
  376. } cairo_line_cap_t;
  377.  
  378. void
  379. cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap);
  380.  
  381. typedef enum _cairo_line_join {
  382.     CAIRO_LINE_JOIN_MITER,
  383.     CAIRO_LINE_JOIN_ROUND,
  384.     CAIRO_LINE_JOIN_BEVEL
  385. } cairo_line_join_t;
  386.  
  387. void
  388. cairo_set_line_join (cairo_t *cr, cairo_line_join_t line_join);
  389.  
  390. void
  391. cairo_set_dash (cairo_t    *cr,
  392.         double    *dashes,
  393.         int     num_dashes,
  394.         double     offset);
  395.  
  396. void
  397. cairo_set_miter_limit (cairo_t *cr, double limit);
  398.  
  399. void
  400. cairo_translate (cairo_t *cr, double tx, double ty);
  401.  
  402. void
  403. cairo_scale (cairo_t *cr, double sx, double sy);
  404.  
  405. void
  406. cairo_rotate (cairo_t *cr, double angle);
  407.  
  408. void
  409. cairo_transform (cairo_t          *cr,
  410.          const cairo_matrix_t *matrix);
  411.  
  412. void
  413. cairo_set_matrix (cairo_t           *cr,
  414.           const cairo_matrix_t *matrix);
  415.  
  416. void
  417. cairo_identity_matrix (cairo_t *cr);
  418.  
  419. void
  420. cairo_user_to_device (cairo_t *cr, double *x, double *y);
  421.  
  422. void
  423. cairo_user_to_device_distance (cairo_t *cr, double *dx, double *dy);
  424.  
  425. void
  426. cairo_device_to_user (cairo_t *cr, double *x, double *y);
  427.  
  428. void
  429. cairo_device_to_user_distance (cairo_t *cr, double *dx, double *dy);
  430.  
  431. /* Path creation functions */
  432. void
  433. cairo_new_path (cairo_t *cr);
  434.  
  435. void
  436. cairo_move_to (cairo_t *cr, double x, double y);
  437.  
  438. void
  439. cairo_line_to (cairo_t *cr, double x, double y);
  440.  
  441. void
  442. cairo_curve_to (cairo_t *cr,
  443.         double x1, double y1,
  444.         double x2, double y2,
  445.         double x3, double y3);
  446.  
  447. void
  448. cairo_arc (cairo_t *cr,
  449.        double xc, double yc,
  450.        double radius,
  451.        double angle1, double angle2);
  452.  
  453. void
  454. cairo_arc_negative (cairo_t *cr,
  455.             double xc, double yc,
  456.             double radius,
  457.             double angle1, double angle2);
  458.  
  459. /* XXX: NYI
  460. void
  461. cairo_arc_to (cairo_t *cr,
  462.           double x1, double y1,
  463.           double x2, double y2,
  464.           double radius);
  465. */
  466.  
  467. void
  468. cairo_rel_move_to (cairo_t *cr, double dx, double dy);
  469.  
  470. void
  471. cairo_rel_line_to (cairo_t *cr, double dx, double dy);
  472.  
  473. void
  474. cairo_rel_curve_to (cairo_t *cr,
  475.             double dx1, double dy1,
  476.             double dx2, double dy2,
  477.             double dx3, double dy3);
  478.  
  479. void
  480. cairo_rectangle (cairo_t *cr,
  481.          double x, double y,
  482.          double width, double height);
  483.  
  484. /* XXX: NYI
  485. void
  486. cairo_stroke_to_path (cairo_t *cr);
  487. */
  488.  
  489. void
  490. cairo_close_path (cairo_t *cr);
  491.  
  492. /* Painting functions */
  493. void
  494. cairo_paint (cairo_t *cr);
  495.  
  496. void
  497. cairo_paint_with_alpha (cairo_t *cr,
  498.             double   alpha);
  499.  
  500. void
  501. cairo_mask (cairo_t         *cr,
  502.         cairo_pattern_t *pattern);
  503.  
  504. void
  505. cairo_mask_surface (cairo_t         *cr,
  506.             cairo_surface_t *surface,
  507.             double           surface_x,
  508.             double           surface_y);
  509.  
  510. void
  511. cairo_stroke (cairo_t *cr);
  512.  
  513. void
  514. cairo_stroke_preserve (cairo_t *cr);
  515.  
  516. void
  517. cairo_fill (cairo_t *cr);
  518.  
  519. void
  520. cairo_fill_preserve (cairo_t *cr);
  521.  
  522. void
  523. cairo_copy_page (cairo_t *cr);
  524.  
  525. void
  526. cairo_show_page (cairo_t *cr);
  527.  
  528. /* Insideness testing */
  529. cairo_bool_t
  530. cairo_in_stroke (cairo_t *cr, double x, double y);
  531.  
  532. cairo_bool_t
  533. cairo_in_fill (cairo_t *cr, double x, double y);
  534.  
  535. /* Rectangular extents */
  536. void
  537. cairo_stroke_extents (cairo_t *cr,
  538.               double *x1, double *y1,
  539.               double *x2, double *y2);
  540.  
  541. void
  542. cairo_fill_extents (cairo_t *cr,
  543.             double *x1, double *y1,
  544.             double *x2, double *y2);
  545.  
  546. /* Clipping */
  547. void
  548. cairo_reset_clip (cairo_t *cr);
  549.  
  550. void
  551. cairo_clip (cairo_t *cr);
  552.  
  553. void
  554. cairo_clip_preserve (cairo_t *cr);
  555.  
  556. /* Font/Text functions */
  557.  
  558. /**
  559.  * cairo_scaled_font_t:
  560.  *
  561.  * A #cairo_scaled_font_t is a font scaled to a particular size and device
  562.  * resolution. A cairo_scaled_font_t is most useful for low-level font
  563.  * usage where a library or application wants to cache a reference
  564.  * to a scaled font to speed up the computation of metrics.
  565.  */
  566. typedef struct _cairo_scaled_font cairo_scaled_font_t;
  567.  
  568. /**
  569.  * cairo_font_face_t:
  570.  *
  571.  * A #cairo_font_face_t specifies all aspects of a font other
  572.  * than the size or font matrix (a font matrix is used to distort
  573.  * a font by sheering it or scaling it unequally in the two
  574.  * directions) . A font face can be set on a #cairo_t by using
  575.  * cairo_set_font_face(); the size and font matrix are set with
  576.  * cairo_set_font_size() and cairo_set_font_matrix().
  577.  */
  578. typedef struct _cairo_font_face cairo_font_face_t;
  579.  
  580. /**
  581.  * cairo_glyph_t:
  582.  * @index: glyph index in the font. The exact interpretation of the
  583.  *      glyph index depends on the font technology being used.
  584.  * @x: the offset in the X direction between the origin used for
  585.  *     drawing or measuring the string and the origin of this glyph.
  586.  * @y: the offset in the Y direction between the origin used for
  587.  *     drawing or measuring the string and the origin of this glyph.
  588.  *
  589.  * The #cairo_glyph_t structure holds information about a single glyph
  590.  * when drawing or measuring text. A font is (in simple terms) a
  591.  * collection of shapes used to draw text. A glyph is one of these
  592.  * shapes. There can be multiple glyphs for a single character
  593.  * (alternates to be used in different contexts, for example), or a
  594.  * glyph can be a <firstterm>ligature</firstterm> of multiple
  595.  * characters. Cairo doesn't expose any way of converting input text
  596.  * into glyphs, so in order to use the Cairo interfaces that take
  597.  * arrays of glyphs, you must directly access the appropriate
  598.  * underlying font system.
  599.  *
  600.  * Note that the offsets given by @x and @y are not cumulative. When
  601.  * drawing or measuring text, each glyph is individually positioned
  602.  * with respect to the overall origin
  603.  **/
  604. typedef struct {
  605.   unsigned long        index;
  606.   double               x;
  607.   double               y;
  608. } cairo_glyph_t;
  609.  
  610. /**
  611.  * cairo_text_extents_t:
  612.  * @x_bearing: the horizontal distance from the origin to the
  613.  *   leftmost part of the glyphs as drawn. Positive if the
  614.  *   glyphs lie entirely to the right of the origin.
  615.  * @y_bearing: the vertical distance from the origin to the
  616.  *   topmost part of the glyphs as drawn. Positive only if the
  617.  *   glyphs lie completely below the origin; will usually be
  618.  *   negative.
  619.  * @width: width of the glyphs as drawn
  620.  * @height: height of the glyphs as drawn
  621.  * @x_advance:distance to advance in the X direction
  622.  *    after drawing these glyphs
  623.  * @y_advance: distance to advance in the Y direction
  624.  *   after drawing these glyphs. Will typically be zero except
  625.  *   for vertical text layout as found in East-Asian languages.
  626.  *
  627.  * The #cairo_text_extents_t structure stores the extents of a single
  628.  * glyph or a string of glyphs in user-space coordinates. Because text
  629.  * extents are in user-space coordinates, they are mostly, but not
  630.  * entirely, independent of the current transformation matrix. If you call
  631.  * <literal>cairo_scale(cr, 2.0, 2.0)</literal>, text will
  632.  * be drawn twice as big, but the reported text extents will not be
  633.  * doubled. They will change slightly due to hinting (so you can't
  634.  * assume that metrics are independent of the transformation matrix),
  635.  * but otherwise will remain unchanged.
  636.  */
  637. typedef struct {
  638.     double x_bearing;
  639.     double y_bearing;
  640.     double width;
  641.     double height;
  642.     double x_advance;
  643.     double y_advance;
  644. } cairo_text_extents_t;
  645.  
  646. /**
  647.  * cairo_font_extents_t:
  648.  * @ascent: the distance that the font extends above the baseline.
  649.  *          Note that this is not always exactly equal to the maximum
  650.  *          of the extents of all the glyphs in the font, but rather
  651.  *          is picked to express the font designer's intent as to
  652.  *          how the font should align with elements above it.
  653.  * @descent: the distance that the font extends below the baseline.
  654.  *           This value is positive for typical fonts that include
  655.  *           portions below the baseline. Note that this is not always
  656.  *           exactly equal to the maximum of the extents of all the
  657.  *           glyphs in the font, but rather is picked to express the
  658.  *           font designer's intent as to how the the font should
  659.  *           align with elements below it.
  660.  * @height: the recommended vertical distance between baselines when
  661.  *          setting consecutive lines of text with the font. This
  662.  *          is greater than @ascent+@descent by a
  663.  *          quantity known as the <firstterm>line spacing</firstterm>
  664.  *          or <firstterm>external leading</firstterm>. When space
  665.  *          is at a premium, most fonts can be set with only
  666.  *          a distance of @ascent+@descent between lines.
  667.  * @max_x_advance: the maximum distance in the X direction that 
  668.  *         the the origin is advanced for any glyph in the font.
  669.  * @max_y_advance: the maximum distance in the Y direction that
  670.  *         the the origin is advanced for any glyph in the font.
  671.  *         this will be zero for normal fonts used for horizontal
  672.  *         writing. (The scripts of East Asia are sometimes written
  673.  *         vertically.)
  674.  *
  675.  * The #cairo_text_extents_t structure stores metric information for
  676.  * a font. Values are given in the current user-space coordinate
  677.  * system.
  678.  *
  679.  * Because font metrics are in user-space coordinates, they are
  680.  * mostly, but not entirely, independent of the current transformation
  681.  * matrix. If you call <literal>cairo_scale(cr, 2.0, 2.0)</literal>,
  682.  * text will be drawn twice as big, but the reported text extents will
  683.  * not be doubled. They will change slightly due to hinting (so you
  684.  * can't assume that metrics are independent of the transformation
  685.  * matrix), but otherwise will remain unchanged.
  686.  */
  687. typedef struct {
  688.     double ascent;
  689.     double descent;
  690.     double height;
  691.     double max_x_advance;
  692.     double max_y_advance;
  693. } cairo_font_extents_t;
  694.  
  695. typedef enum _cairo_font_slant {
  696.   CAIRO_FONT_SLANT_NORMAL,
  697.   CAIRO_FONT_SLANT_ITALIC,
  698.   CAIRO_FONT_SLANT_OBLIQUE
  699. } cairo_font_slant_t;
  700.   
  701. typedef enum _cairo_font_weight {
  702.   CAIRO_FONT_WEIGHT_NORMAL,
  703.   CAIRO_FONT_WEIGHT_BOLD
  704. } cairo_font_weight_t;
  705.  
  706. /**
  707.  * cairo_subpixel_order_t:
  708.  * @CAIRO_SUBPIXEL_ORDER_DEFAULT: Use the default subpixel order for
  709.  *   for the target device
  710.  * @CAIRO_SUBPIXEL_ORDER_RGB: Subpixel elements are arranged horizontally
  711.  *   with red at the left
  712.  * @CAIRO_SUBPIXEL_ORDER_BGR:  Subpixel elements are arranged horizontally
  713.  *   with blue at the left
  714.  * @CAIRO_SUBPIXEL_ORDER_VRGB: Subpixel elements are arranged vertically
  715.  *   with red at the top
  716.  * @CAIRO_SUBPIXEL_ORDER_VBGR: Subpixel elements are arranged vertically
  717.  *   with blue at the top
  718.  * 
  719.  * The subpixel order specifies the order of color elements within
  720.  * each pixel on the display device when rendering with an
  721.  * antialiasing mode of %CAIRO_ANTIALIAS_SUBPIXEL.
  722.  **/
  723. typedef enum _cairo_subpixel_order {
  724.     CAIRO_SUBPIXEL_ORDER_DEFAULT,
  725.     CAIRO_SUBPIXEL_ORDER_RGB,
  726.     CAIRO_SUBPIXEL_ORDER_BGR,
  727.     CAIRO_SUBPIXEL_ORDER_VRGB,
  728.     CAIRO_SUBPIXEL_ORDER_VBGR
  729. } cairo_subpixel_order_t;
  730.  
  731. /**
  732.  * cairo_hint_style_t:
  733.  * @CAIRO_HINT_STYLE_DEFAULT: Use the default hint style for
  734.  *   for font backend and target device
  735.  * @CAIRO_HINT_STYLE_NONE: Do not hint outlines
  736.  * @CAIRO_HINT_STYLE_SLIGHT: Hint outlines slightly to improve
  737.  *   contrast while retaining good fidelity to the original
  738.  *   shapes.
  739.  * @CAIRO_HINT_STYLE_MEDIUM: Hint outlines with medium strength
  740.  *   giving a compromise between fidelity to the original shapes
  741.  *   and contrast
  742.  * @CAIRO_HINT_STYLE_FULL: Hint outlines to maximize contrast
  743.  *
  744.  * Specifies the type of hinting to do on font outlines. Hinting
  745.  * is the process of fitting outlines to the pixel grid in order
  746.  * to improve the appearance of the result. Since hinting outlines
  747.  * involves distorting them, it also reduces the faithfulness
  748.  * to the original outline shapes. Not all of the outline hinting
  749.  * styles are supported by all font backends.
  750.  */
  751. typedef enum _cairo_hint_style {
  752.     CAIRO_HINT_STYLE_DEFAULT,
  753.     CAIRO_HINT_STYLE_NONE,
  754.     CAIRO_HINT_STYLE_SLIGHT,
  755.     CAIRO_HINT_STYLE_MEDIUM,
  756.     CAIRO_HINT_STYLE_FULL
  757. } cairo_hint_style_t;
  758.  
  759. /**
  760.  * cairo_hint_metrics_t:
  761.  * @CAIRO_HINT_METRICS_DEFAULT: Hint metrics in the default
  762.  *  manner for the font backend and target device
  763.  * @CAIRO_HINT_METRICS_OFF: Do not hint font metrics
  764.  * @CAIRO_HINT_METRICS_ON: Hint font metrics
  765.  *
  766.  * Specifies whether to hint font metrics; hinting font metrics
  767.  * means quantizing them so that they are integer values in
  768.  * device space. Doing this improves the consistency of
  769.  * letter and line spacing, however it also means that text
  770.  * will be laid out differently at different zoom factors.
  771.  */
  772. typedef enum _cairo_hint_metrics {
  773.     CAIRO_HINT_METRICS_DEFAULT,
  774.     CAIRO_HINT_METRICS_OFF,
  775.     CAIRO_HINT_METRICS_ON
  776. } cairo_hint_metrics_t;
  777.  
  778. typedef struct _cairo_font_options cairo_font_options_t;
  779.  
  780. cairo_font_options_t *
  781. cairo_font_options_create (void);
  782.  
  783. cairo_font_options_t *
  784. cairo_font_options_copy (const cairo_font_options_t *original);
  785.  
  786. void 
  787. cairo_font_options_destroy (cairo_font_options_t *options);
  788.  
  789. cairo_status_t
  790. cairo_font_options_status (cairo_font_options_t *options);
  791.  
  792. void
  793. cairo_font_options_merge (cairo_font_options_t       *options,
  794.               const cairo_font_options_t *other);
  795. cairo_bool_t
  796. cairo_font_options_equal (const cairo_font_options_t *options,
  797.               const cairo_font_options_t *other);
  798.  
  799. unsigned long
  800. cairo_font_options_hash (const cairo_font_options_t *options);
  801.  
  802. void
  803. cairo_font_options_set_antialias (cairo_font_options_t *options,
  804.                   cairo_antialias_t     antialias);
  805. cairo_antialias_t
  806. cairo_font_options_get_antialias (const cairo_font_options_t *options);
  807.  
  808. void
  809. cairo_font_options_set_subpixel_order (cairo_font_options_t   *options,
  810.                        cairo_subpixel_order_t  subpixel_order);
  811. cairo_subpixel_order_t
  812. cairo_font_options_get_subpixel_order (const cairo_font_options_t *options);
  813.              
  814. void
  815. cairo_font_options_set_hint_style (cairo_font_options_t *options,
  816.                    cairo_hint_style_t     hint_style);
  817. cairo_hint_style_t
  818. cairo_font_options_get_hint_style (const cairo_font_options_t *options);
  819.  
  820. void
  821. cairo_font_options_set_hint_metrics (cairo_font_options_t *options,
  822.                      cairo_hint_metrics_t  hint_metrics);
  823. cairo_hint_metrics_t
  824. cairo_font_options_get_hint_metrics (const cairo_font_options_t *options);
  825.  
  826.  
  827. /* This interface is for dealing with text as text, not caring about the
  828.    font object inside the the cairo_t. */
  829.  
  830. void
  831. cairo_select_font_face (cairo_t              *cr, 
  832.             const char           *family, 
  833.             cairo_font_slant_t   slant, 
  834.             cairo_font_weight_t  weight);
  835.  
  836. void
  837. cairo_set_font_size (cairo_t *cr, double size);
  838.  
  839. void
  840. cairo_set_font_matrix (cairo_t            *cr,
  841.                const cairo_matrix_t *matrix);
  842.  
  843. void
  844. cairo_get_font_matrix (cairo_t *cr,
  845.                cairo_matrix_t *matrix);
  846.  
  847. void
  848. cairo_set_font_options (cairo_t                    *cr,
  849.             const cairo_font_options_t *options);
  850.  
  851. void
  852. cairo_get_font_options (cairo_t              *cr,
  853.             cairo_font_options_t *options);
  854.  
  855. void
  856. cairo_show_text (cairo_t *cr, const char *utf8);
  857.  
  858. void
  859. cairo_show_glyphs (cairo_t *cr, cairo_glyph_t *glyphs, int num_glyphs);
  860.  
  861. cairo_font_face_t *
  862. cairo_get_font_face (cairo_t *cr);
  863.  
  864. void
  865. cairo_font_extents (cairo_t              *cr, 
  866.             cairo_font_extents_t *extents);
  867.  
  868. void
  869. cairo_set_font_face (cairo_t *cr, cairo_font_face_t *font_face);
  870.  
  871. void
  872. cairo_text_extents (cairo_t              *cr,
  873.             const char         *utf8,
  874.             cairo_text_extents_t *extents);
  875.  
  876. void
  877. cairo_glyph_extents (cairo_t               *cr,
  878.              cairo_glyph_t         *glyphs, 
  879.              int                   num_glyphs,
  880.              cairo_text_extents_t  *extents);
  881.  
  882. void
  883. cairo_text_path  (cairo_t *cr, const char *utf8);
  884.  
  885. void
  886. cairo_glyph_path (cairo_t *cr, cairo_glyph_t *glyphs, int num_glyphs);
  887.  
  888. /* Generic identifier for a font style */
  889.  
  890. cairo_font_face_t *
  891. cairo_font_face_reference (cairo_font_face_t *font_face);
  892.  
  893. void
  894. cairo_font_face_destroy (cairo_font_face_t *font_face);
  895.  
  896. cairo_status_t
  897. cairo_font_face_status (cairo_font_face_t *font_face);
  898.  
  899. void *
  900. cairo_font_face_get_user_data (cairo_font_face_t       *font_face,
  901.                    const cairo_user_data_key_t *key);
  902.  
  903. cairo_status_t
  904. cairo_font_face_set_user_data (cairo_font_face_t       *font_face,
  905.                    const cairo_user_data_key_t *key,
  906.                    void               *user_data,
  907.                    cairo_destroy_func_t        destroy);
  908.  
  909. /* Portable interface to general font features. */
  910.  
  911. cairo_scaled_font_t *
  912. cairo_scaled_font_create (cairo_font_face_t          *font_face,
  913.               const cairo_matrix_t       *font_matrix,
  914.               const cairo_matrix_t       *ctm,
  915.               const cairo_font_options_t *options);
  916.  
  917. cairo_scaled_font_t *
  918. cairo_scaled_font_reference (cairo_scaled_font_t *scaled_font);
  919.  
  920. void
  921. cairo_scaled_font_destroy (cairo_scaled_font_t *scaled_font);
  922.  
  923. cairo_status_t
  924. cairo_scaled_font_status (cairo_scaled_font_t *scaled_font);
  925.  
  926. void
  927. cairo_scaled_font_extents (cairo_scaled_font_t  *scaled_font,
  928.                cairo_font_extents_t *extents);
  929.  
  930. void
  931. cairo_scaled_font_glyph_extents (cairo_scaled_font_t   *scaled_font,
  932.                  cairo_glyph_t         *glyphs, 
  933.                  int                   num_glyphs,
  934.                  cairo_text_extents_t  *extents);
  935.  
  936. /* Query functions */
  937.  
  938. cairo_operator_t
  939. cairo_get_operator (cairo_t *cr);
  940.  
  941. cairo_pattern_t *
  942. cairo_get_source (cairo_t *cr);
  943.  
  944. double
  945. cairo_get_tolerance (cairo_t *cr);
  946.  
  947. cairo_antialias_t
  948. cairo_get_antialias (cairo_t *cr);
  949.  
  950. void
  951. cairo_get_current_point (cairo_t *cr, double *x, double *y);
  952.  
  953. cairo_fill_rule_t
  954. cairo_get_fill_rule (cairo_t *cr);
  955.  
  956. double
  957. cairo_get_line_width (cairo_t *cr);
  958.  
  959. cairo_line_cap_t
  960. cairo_get_line_cap (cairo_t *cr);
  961.  
  962. cairo_line_join_t
  963. cairo_get_line_join (cairo_t *cr);
  964.  
  965. double
  966. cairo_get_miter_limit (cairo_t *cr);
  967.  
  968. /* XXX: How to do cairo_get_dash??? Do we want to switch to a cairo_dash object? */
  969.  
  970. void
  971. cairo_get_matrix (cairo_t *cr, cairo_matrix_t *matrix);
  972.  
  973. cairo_surface_t *
  974. cairo_get_target (cairo_t *cr);
  975.  
  976. typedef enum _cairo_path_data_type {
  977.     CAIRO_PATH_MOVE_TO,
  978.     CAIRO_PATH_LINE_TO,
  979.     CAIRO_PATH_CURVE_TO,
  980.     CAIRO_PATH_CLOSE_PATH
  981. } cairo_path_data_type_t;
  982.  
  983. /**
  984.  * cairo_path_data_t:
  985.  *
  986.  * #cairo_path_data_t is used to represent the path data inside a
  987.  * #cairo_path_t.
  988.  *
  989.  * The data structure is designed to try to balance the demands of
  990.  * efficiency and ease-of-use. A path is represented as an array of
  991.  * #cairo_path_data_t, which is a union of headers and points.
  992.  *
  993.  * Each portion of the path is represented by one or more elements in
  994.  * the array, (one header followed by 0 or more points). The length
  995.  * value of the header is the number of array elements for the current
  996.  * portion including the header, (ie. length == 1 + # of points), and
  997.  * where the number of points for each element type must be as
  998.  * follows:
  999.  *
  1000.  * <programlisting>
  1001.  *     %CAIRO_PATH_MOVE_TO:     1 point
  1002.  *     %CAIRO_PATH_LINE_TO:     1 point
  1003.  *     %CAIRO_PATH_CURVE_TO:    3 points
  1004.  *     %CAIRO_PATH_CLOSE_PATH:  0 points
  1005.  * </programlisting>
  1006.  *
  1007.  * The semantics and ordering of the coordinate values are consistent
  1008.  * with cairo_move_to(), cairo_line_to(), cairo_curve_to(), and
  1009.  * cairo_close_path().
  1010.  *
  1011.  * Here is sample code for iterating through a #cairo_path_t:
  1012.  *
  1013.  * <informalexample><programlisting>
  1014.  *      int i;
  1015.  *      cairo_path_t *path;
  1016.  *      cairo_path_data_t *data;
  1017.  *  
  1018.  *      path = cairo_copy_path (cr);
  1019.  *  
  1020.  *      for (i=0; i < path->num_data; i += path->data[i].header.length) {
  1021.  *          data = &path->data[i];
  1022.  *          switch (data->header.type) {
  1023.  *          case CAIRO_PATH_MOVE_TO:
  1024.  *              do_move_to_things (data[1].point.x, data[1].point.y);
  1025.  *              break;
  1026.  *          case CAIRO_PATH_LINE_TO:
  1027.  *              do_line_to_things (data[1].point.x, data[1].point.y);
  1028.  *              break;
  1029.  *          case CAIRO_PATH_CURVE_TO:
  1030.  *              do_curve_to_things (data[1].point.x, data[1].point.y,
  1031.  *                                  data[2].point.x, data[2].point.y,
  1032.  *                                  data[3].point.x, data[3].point.y);
  1033.  *              break;
  1034.  *          case CAIRO_PATH_CLOSE_PATH:
  1035.  *              do_close_path_things ();
  1036.  *              break;
  1037.  *          }
  1038.  *      }
  1039.  *      cairo_path_destroy (path);
  1040.  * </programlisting></informalexample>
  1041.  **/
  1042. typedef union _cairo_path_data_t cairo_path_data_t;
  1043. union _cairo_path_data_t {
  1044.     struct {
  1045.     cairo_path_data_type_t type;
  1046.     int length;
  1047.     } header;
  1048.     struct {
  1049.     double x, y;
  1050.     } point;
  1051. };
  1052.  
  1053. /**
  1054.  * cairo_path_t:
  1055.  * @status: the current error status
  1056.  * @data: the elements in the path
  1057.  * @num_data: the number of elements in the data array
  1058.  *
  1059.  * A data structure for holding a path. This data structure serves as
  1060.  * the return value for cairo_copy_path_data() and
  1061.  * cairo_copy_path_data_flat() as well the input value for
  1062.  * cairo_append_path().
  1063.  *
  1064.  * See #cairo_path_data_t for hints on how to iterate over the
  1065.  * actual data within the path.
  1066.  *
  1067.  * The num_data member gives the number of elements in the data
  1068.  * array. This number is larger than the number of independent path
  1069.  * portions (defined in #cairo_path_data_type_t), since the data
  1070.  * includes both headers and coordinates for each portion.
  1071.  **/
  1072. typedef struct cairo_path {
  1073.     cairo_status_t status;
  1074.     cairo_path_data_t *data;
  1075.     int num_data;
  1076. } cairo_path_t;
  1077.  
  1078. cairo_path_t *
  1079. cairo_copy_path (cairo_t *cr);
  1080.  
  1081. cairo_path_t *
  1082. cairo_copy_path_flat (cairo_t *cr);
  1083.  
  1084. void
  1085. cairo_append_path (cairo_t    *cr,
  1086.            cairo_path_t *path);
  1087.  
  1088. void
  1089. cairo_path_destroy (cairo_path_t *path);
  1090.  
  1091. /* Error status queries */
  1092.  
  1093. cairo_status_t
  1094. cairo_status (cairo_t *cr);
  1095.  
  1096. const char *
  1097. cairo_status_to_string (cairo_status_t status);
  1098.  
  1099. /* Surface manipulation */
  1100.  
  1101. /**
  1102.  * cairo_content_t
  1103.  * @CAIRO_CONTENT_COLOR: The surface will hold color content only.
  1104.  * @CAIRO_CONTENT_ALPHA: The surface will hold alpha content only.
  1105.  * @CAIRO_CONTENT_COLOR_ALPHA: The surface will hold color and alpha content.
  1106.  *
  1107.  * @cairo_content_t is used to describe the content that a surface will
  1108.  * contain, whether color information, alpha information (translucence
  1109.  * vs. opacity), or both.
  1110.  *
  1111.  * Note: The large values here are designed to keep cairo_content_t
  1112.  * values distinct from cairo_format_t values so that the
  1113.  * implementation can detect the error if users confuse the two types.
  1114.  */
  1115. typedef enum _cairo_content {
  1116.     CAIRO_CONTENT_COLOR        = 0x1000,
  1117.     CAIRO_CONTENT_ALPHA        = 0x2000,
  1118.     CAIRO_CONTENT_COLOR_ALPHA    = 0x3000
  1119. } cairo_content_t;
  1120.  
  1121. cairo_surface_t *
  1122. cairo_surface_create_similar (cairo_surface_t  *other,
  1123.                   cairo_content_t    content,
  1124.                   int        width,
  1125.                   int        height);
  1126.  
  1127. cairo_surface_t *
  1128. cairo_surface_reference (cairo_surface_t *surface);
  1129.  
  1130. void
  1131. cairo_surface_destroy (cairo_surface_t *surface);
  1132.  
  1133. cairo_status_t
  1134. cairo_surface_status (cairo_surface_t *surface);
  1135.  
  1136. void
  1137. cairo_surface_finish (cairo_surface_t *surface);
  1138.  
  1139. #if CAIRO_HAS_PNG_FUNCTIONS
  1140.  
  1141. cairo_status_t
  1142. cairo_surface_write_to_png (cairo_surface_t    *surface,
  1143.                 const char        *filename);
  1144.  
  1145. cairo_status_t
  1146. cairo_surface_write_to_png_stream (cairo_surface_t    *surface,
  1147.                    cairo_write_func_t    write_func,
  1148.                    void            *closure);
  1149.  
  1150. #endif
  1151.  
  1152. void *
  1153. cairo_surface_get_user_data (cairo_surface_t         *surface,
  1154.                  const cairo_user_data_key_t *key);
  1155.  
  1156. cairo_status_t
  1157. cairo_surface_set_user_data (cairo_surface_t         *surface,
  1158.                  const cairo_user_data_key_t *key,
  1159.                  void             *user_data,
  1160.                  cairo_destroy_func_t     destroy);
  1161.  
  1162. void
  1163. cairo_surface_get_font_options (cairo_surface_t      *surface,
  1164.                 cairo_font_options_t *options);
  1165.  
  1166. void
  1167. cairo_surface_flush (cairo_surface_t *surface);
  1168.  
  1169. void
  1170. cairo_surface_mark_dirty (cairo_surface_t *surface);
  1171.  
  1172. void
  1173. cairo_surface_mark_dirty_rectangle (cairo_surface_t *surface,
  1174.                     int              x,
  1175.                     int              y,
  1176.                     int              width,
  1177.                     int              height);
  1178.  
  1179. void
  1180. cairo_surface_set_device_offset (cairo_surface_t *surface,
  1181.                  double           x_offset,
  1182.                  double           y_offset);
  1183.  
  1184. /* Image-surface functions */
  1185.  
  1186. /**
  1187.  * cairo_format_t
  1188.  * @CAIRO_FORMAT_ARGB32: each pixel is a 32-bit quantity, with
  1189.  *   alpha in the upper 8 bits, then red, then green, then blue.
  1190.  *   The 32-bit quantities are stored native-endian. Pre-multiplied
  1191.  *   alpha is used. (That is, 50% transparent red is 0x80800000,
  1192.  *   not 0x80ff0000.)
  1193.  * @CAIRO_FORMAT_RGB24: each pixel is a 32-bit quantity, with
  1194.  *   the upper 8 bits unused. Red, Green, and Blue are stored
  1195.  *   in the remaining 24 bits in that order.
  1196.  * @CAIRO_FORMAT_A8: each pixel is a 8-bit quantity holding
  1197.  *   an alpha value.
  1198.  * @CAIRO_FORMAT_A1: each pixel is a 1-bit quantity holding
  1199.  *   an alpha value. Pixels are packed together into 32-bit
  1200.  *   quantities. The ordering of the bits matches the
  1201.  *   endianess of the platform. On a big-endian machine, the
  1202.  *   first pixel is in the uppermost bit, on a little-endian
  1203.  *   machine the first pixel is in the least-significant bit.
  1204.  *
  1205.  * #cairo_format_t is used to identify the memory format of
  1206.  * image data.
  1207.  */
  1208. typedef enum _cairo_format {
  1209.     CAIRO_FORMAT_ARGB32,
  1210.     CAIRO_FORMAT_RGB24,
  1211.     CAIRO_FORMAT_A8,
  1212.     CAIRO_FORMAT_A1
  1213. } cairo_format_t;
  1214.  
  1215. cairo_surface_t *
  1216. cairo_image_surface_create (cairo_format_t    format,
  1217.                 int            width,
  1218.                 int            height);
  1219.  
  1220. cairo_surface_t *
  1221. cairo_image_surface_create_for_data (unsigned char           *data,
  1222.                      cairo_format_t        format,
  1223.                      int            width,
  1224.                      int            height,
  1225.                      int            stride);
  1226.  
  1227. int
  1228. cairo_image_surface_get_width (cairo_surface_t *surface);
  1229.  
  1230. int
  1231. cairo_image_surface_get_height (cairo_surface_t *surface);
  1232.  
  1233. #if CAIRO_HAS_PNG_FUNCTIONS
  1234.  
  1235. cairo_surface_t *
  1236. cairo_image_surface_create_from_png (const char    *filename);
  1237.  
  1238. cairo_surface_t *
  1239. cairo_image_surface_create_from_png_stream (cairo_read_func_t    read_func,
  1240.                         void        *closure);
  1241.  
  1242. #endif
  1243.  
  1244. /* Pattern creation functions */
  1245.  
  1246. cairo_pattern_t *
  1247. cairo_pattern_create_rgb (double red, double green, double blue);
  1248.  
  1249. cairo_pattern_t *
  1250. cairo_pattern_create_rgba (double red, double green, double blue,
  1251.                double alpha);
  1252.  
  1253. cairo_pattern_t *
  1254. cairo_pattern_create_for_surface (cairo_surface_t *surface);
  1255.  
  1256. cairo_pattern_t *
  1257. cairo_pattern_create_linear (double x0, double y0,
  1258.                  double x1, double y1);
  1259.  
  1260. cairo_pattern_t *
  1261. cairo_pattern_create_radial (double cx0, double cy0, double radius0,
  1262.                  double cx1, double cy1, double radius1);
  1263.  
  1264. cairo_pattern_t *
  1265. cairo_pattern_reference (cairo_pattern_t *pattern);
  1266.  
  1267. void
  1268. cairo_pattern_destroy (cairo_pattern_t *pattern);
  1269.   
  1270. cairo_status_t
  1271. cairo_pattern_status (cairo_pattern_t *pattern);
  1272.  
  1273. void
  1274. cairo_pattern_add_color_stop_rgb (cairo_pattern_t *pattern,
  1275.                   double offset,
  1276.                   double red, double green, double blue);
  1277.  
  1278. void
  1279. cairo_pattern_add_color_stop_rgba (cairo_pattern_t *pattern,
  1280.                    double offset,
  1281.                    double red, double green, double blue,
  1282.                    double alpha);
  1283.  
  1284. void
  1285. cairo_pattern_set_matrix (cairo_pattern_t      *pattern,
  1286.               const cairo_matrix_t *matrix);
  1287.  
  1288. void
  1289. cairo_pattern_get_matrix (cairo_pattern_t *pattern,
  1290.               cairo_matrix_t  *matrix);
  1291.  
  1292. typedef enum _cairo_extend {
  1293.     CAIRO_EXTEND_NONE,
  1294.     CAIRO_EXTEND_REPEAT,
  1295.     CAIRO_EXTEND_REFLECT
  1296. } cairo_extend_t;
  1297.  
  1298. void
  1299. cairo_pattern_set_extend (cairo_pattern_t *pattern, cairo_extend_t extend);
  1300.  
  1301. cairo_extend_t
  1302. cairo_pattern_get_extend (cairo_pattern_t *pattern);
  1303.  
  1304. typedef enum _cairo_filter {
  1305.     CAIRO_FILTER_FAST,
  1306.     CAIRO_FILTER_GOOD,
  1307.     CAIRO_FILTER_BEST,
  1308.     CAIRO_FILTER_NEAREST,
  1309.     CAIRO_FILTER_BILINEAR,
  1310.     CAIRO_FILTER_GAUSSIAN
  1311. } cairo_filter_t;
  1312.   
  1313. void
  1314. cairo_pattern_set_filter (cairo_pattern_t *pattern, cairo_filter_t filter);
  1315.  
  1316. cairo_filter_t
  1317. cairo_pattern_get_filter (cairo_pattern_t *pattern);
  1318.  
  1319. /* Matrix functions */
  1320.  
  1321. void
  1322. cairo_matrix_init (cairo_matrix_t *matrix,
  1323.            double  xx, double  yx,
  1324.            double  xy, double  yy,
  1325.            double  x0, double  y0);
  1326.  
  1327. void
  1328. cairo_matrix_init_identity (cairo_matrix_t *matrix);
  1329.  
  1330. void
  1331. cairo_matrix_init_translate (cairo_matrix_t *matrix,
  1332.                  double tx, double ty);
  1333.  
  1334. void
  1335. cairo_matrix_init_scale (cairo_matrix_t *matrix,
  1336.              double sx, double sy);
  1337.  
  1338. void
  1339. cairo_matrix_init_rotate (cairo_matrix_t *matrix,
  1340.               double radians);
  1341.  
  1342. void
  1343. cairo_matrix_translate (cairo_matrix_t *matrix, double tx, double ty);
  1344.  
  1345. void
  1346. cairo_matrix_scale (cairo_matrix_t *matrix, double sx, double sy);
  1347.  
  1348. void
  1349. cairo_matrix_rotate (cairo_matrix_t *matrix, double radians);
  1350.  
  1351. cairo_status_t
  1352. cairo_matrix_invert (cairo_matrix_t *matrix);
  1353.  
  1354. void
  1355. cairo_matrix_multiply (cairo_matrix_t        *result,
  1356.                const cairo_matrix_t *a,
  1357.                const cairo_matrix_t *b);
  1358.  
  1359. /* XXX: Need a new name here perhaps. */
  1360. void
  1361. cairo_matrix_transform_distance (const cairo_matrix_t *matrix,
  1362.                  double *dx, double *dy);
  1363.  
  1364. /* XXX: Need a new name here perhaps. */
  1365. void
  1366. cairo_matrix_transform_point (const cairo_matrix_t *matrix,
  1367.                   double *x, double *y);
  1368.  
  1369. #ifndef _CAIROINT_H_
  1370.  
  1371. /* Obsolete functions. These definitions exist to coerce the compiler
  1372.  * into providing a little bit of guidance with its error
  1373.  * messages. The idea is to help users port their old code without
  1374.  * having to dig through lots of documentation.
  1375.  *
  1376.  * The first set of REPLACED_BY functions is for functions whose names
  1377.  * have just been changed. So fixing these up is mechanical, (and
  1378.  * automated by means of the cairo/util/cairo-api-update script.
  1379.  *
  1380.  * The second set of DEPRECATED_BY functions is for functions where
  1381.  * the replacement is used in a different way, (ie. different
  1382.  * arguments, multiple functions instead of one, etc). Fixing these up
  1383.  * will require a bit more work on the user's part, (and hopefully we
  1384.  * can get cairo-api-update to find these and print some guiding
  1385.  * information).
  1386.  */
  1387. #define cairo_current_font_extents   cairo_current_font_extents_REPLACED_BY_cairo_font_extents
  1388. #define cairo_get_font_extents       cairo_get_font_extents_REPLACED_BY_cairo_font_extents
  1389. #define cairo_current_operator       cairo_current_operator_REPLACED_BY_cairo_get_operator
  1390. #define cairo_current_tolerance         cairo_current_tolerance_REPLACED_BY_cairo_get_tolerance
  1391. #define cairo_current_point         cairo_current_point_REPLACED_BY_cairo_get_current_point
  1392. #define cairo_current_fill_rule         cairo_current_fill_rule_REPLACED_BY_cairo_get_fill_rule
  1393. #define cairo_current_line_width     cairo_current_line_width_REPLACED_BY_cairo_get_line_width
  1394. #define cairo_current_line_cap       cairo_current_line_cap_REPLACED_BY_cairo_get_line_cap
  1395. #define cairo_current_line_join      cairo_current_line_join_REPLACED_BY_cairo_get_line_join
  1396. #define cairo_current_miter_limit    cairo_current_miter_limit_REPLACED_BY_cairo_get_miter_limit
  1397. #define cairo_current_matrix         cairo_current_matrix_REPLACED_BY_cairo_get_matrix
  1398. #define cairo_current_target_surface cairo_current_target_surface_REPLACED_BY_cairo_get_target
  1399. #define cairo_get_status             cairo_get_status_REPLACED_BY_cairo_status
  1400. #define cairo_concat_matrix         cairo_concat_matrix_REPLACED_BY_cairo_transform
  1401. #define cairo_scale_font                 cairo_scale_font_REPLACED_BY_cairo_set_font_size
  1402. #define cairo_select_font                cairo_select_font_REPLACED_BY_cairo_select_font_face
  1403. #define cairo_transform_font             cairo_transform_font_REPLACED_BY_cairo_set_font_matrix
  1404. #define cairo_transform_point         cairo_transform_point_REPLACED_BY_cairo_user_to_device
  1405. #define cairo_transform_distance     cairo_transform_distance_REPLACED_BY_cairo_user_to_device_distance
  1406. #define cairo_inverse_transform_point     cairo_inverse_transform_point_REPLACED_BY_cairo_device_to_user
  1407. #define cairo_inverse_transform_distance cairo_inverse_transform_distance_REPLACED_BY_cairo_device_to_user_distance
  1408. #define cairo_init_clip             cairo_init_clip_REPLACED_BY_cairo_reset_clip
  1409. #define cairo_surface_create_for_image     cairo_surface_create_for_image_REPLACED_BY_cairo_image_surface_create_for_data
  1410. #define cairo_default_matrix         cairo_default_matrix_REPLACED_BY_cairo_identity_matrix
  1411. #define cairo_matrix_set_affine         cairo_matrix_set_affine_REPLACED_BY_cairo_matrix_init
  1412. #define cairo_matrix_set_identity     cairo_matrix_set_identity_REPLACED_BY_cairo_matrix_init_identity
  1413. #define cairo_pattern_add_color_stop     cairo_pattern_add_color_stop_REPLACED_BY_cairo_pattern_add_color_stop_rgba
  1414. #define cairo_set_rgb_color         cairo_set_rgb_color_REPLACED_BY_cairo_set_source_rgb
  1415. #define cairo_set_pattern         cairo_set_pattern_REPLACED_BY_cairo_set_source
  1416. #define cairo_xlib_surface_create_for_pixmap_with_visual    cairo_xlib_surface_create_for_pixmap_with_visual_REPLACED_BY_cairo_xlib_surface_create
  1417. #define cairo_xlib_surface_create_for_window_with_visual    cairo_xlib_surface_create_for_window_with_visual_REPLACED_BY_cairo_xlib_surface_create
  1418. #define cairo_xcb_surface_create_for_pixmap_with_visual    cairo_xcb_surface_create_for_pixmap_with_visual_REPLACED_BY_cairo_xcb_surface_create
  1419. #define cairo_xcb_surface_create_for_window_with_visual    cairo_xcb_surface_create_for_window_with_visual_REPLACED_BY_cairo_xcb_surface_create
  1420.  
  1421.  
  1422. #define cairo_current_path         cairo_current_path_DEPRECATED_BY_cairo_copy_path
  1423. #define cairo_current_path_flat         cairo_current_path_flat_DEPRECATED_BY_cairo_copy_path_flat
  1424. #define cairo_get_path             cairo_get_path_DEPRECATED_BY_cairo_copy_path
  1425. #define cairo_get_path_flat         cairo_get_path_flat_DEPRECATED_BY_cairo_get_path_flat
  1426. #define cairo_set_alpha             cairo_set_alpha_DEPRECATED_BY_cairo_set_source_rgba_OR_cairo_paint_with_alpha
  1427. #define cairo_show_surface         cairo_show_surface_DEPRECATED_BY_cairo_set_source_surface_AND_cairo_paint
  1428. #define cairo_copy             cairo_copy_DEPRECATED_BY_cairo_create_AND_MANY_INDIVIDUAL_FUNCTIONS
  1429. #define cairo_surface_set_repeat    cairo_surface_set_repeat_DEPRECATED_BY_cairo_pattern_set_extend
  1430. #define cairo_surface_set_matrix    cairo_surface_set_matrix_DEPRECATED_BY_cairo_pattern_set_matrix
  1431. #define cairo_surface_get_matrix    cairo_surface_get_matrix_DEPRECATED_BY_cairo_pattern_get_matrix
  1432. #define cairo_surface_set_filter    cairo_surface_set_filter_DEPRECATED_BY_cairo_pattern_set_filter
  1433. #define cairo_surface_get_filter    cairo_surface_get_filter_DEPRECATED_BY_cairo_pattern_get_filter
  1434. #define cairo_matrix_create        cairo_matrix_create_DEPRECATED_BY_cairo_matrix_t
  1435. #define cairo_matrix_destroy        cairo_matrix_destroy_DEPRECATED_BY_cairo_matrix_t
  1436. #define cairo_matrix_copy        cairo_matrix_copy_DEPRECATED_BY_cairo_matrix_t
  1437. #define cairo_matrix_get_affine        cairo_matrix_get_affine_DEPRECATED_BY_cairo_matrix_t
  1438. #define cairo_set_target_surface    cairo_set_target_surface_DEPRECATED_BY_cairo_create
  1439. #define cairo_set_target_glitz        cairo_set_target_glitz_DEPRECATED_BY_cairo_glitz_surface_create
  1440. #define cairo_set_target_image        cairo_set_target_image_DEPRECATED_BY_cairo_image_surface_create_for_data
  1441. #define cairo_set_target_pdf        cairo_set_target_pdf_DEPRECATED_BY_cairo_pdf_surface_create
  1442. #define cairo_set_target_png        cairo_set_target_png_DEPRECATED_BY_cairo_surface_write_to_png
  1443. #define cairo_set_target_ps        cairo_set_target_ps_DEPRECATED_BY_cairo_ps_surface_create
  1444. #define cairo_set_target_quartz        cairo_set_target_quartz_DEPRECATED_BY_cairo_quartz_surface_create
  1445. #define cairo_set_target_win32        cairo_set_target_win32_DEPRECATED_BY_cairo_win32_surface_create
  1446. #define cairo_set_target_xcb        cairo_set_target_xcb_DEPRECATED_BY_cairo_xcb_surface_create
  1447. #define cairo_set_target_drawable    cairo_set_target_drawable_DEPRECATED_BY_cairo_xlib_surface_create
  1448. #define cairo_get_status_string        cairo_get_status_string_DEPRECATED_BY_cairo_status_AND_cairo_status_to_string
  1449. #define cairo_status_string        cairo_status_string_DEPRECATED_BY_cairo_status_AND_cairo_status_to_string
  1450.  
  1451. #endif
  1452.  
  1453. CAIRO_END_DECLS
  1454.  
  1455. #endif /* CAIRO_H */
  1456.